<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 transitional//EN">
<html>
<head>
<title>Grid Element (Eclipse BIRT ROM Documentation)</title>
<link rel="stylesheet" href="../style/style.css" type="text/css"/>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head>
<body>
<p class="title">Eclipse BIRT Report Object Model (ROM)</p>
<p class="subtitle">Grid Element</p>
<h1>Element Overview</h1>
<div class="section-text">
Represents a Grid item, it's divided into a series of rows and columns.</div>
<h3>Details</h3>

<table class="detail-table">
<tr><td>Display Name:</td>
<td>Grid</td></tr>
<tr><td>Since:</td>
<td>1.0</td></tr>
<tr><td>XML Element:</td>
<td><code>grid</code></td></tr>
<tr><td>Extends:</td>
<td><a href="ReportItem.html">ReportItem</a></td></tr>
<tr><td>Extendable:</td>
<td>Yes</td></tr>
<tr><td>Abstract:</td>
<td>No</td></tr>
<tr><td>Name Space:</td>
<td>Report Items</td></tr>
<tr><td>Name Requirement:</td>
<td>Optional</td></tr>
<tr><td>Allows User Properties:</td>
<td>Yes</td></tr>
<tr><td>Has Style:</td>
<td>Yes</td></tr>
<tr><td>Default Style:</td>
<td><a href="../styles.html#grid">grid</a></td></tr>
</table>

<h3>Property Summary</h3>

<dl class="section-text">
<dt><a href="#Property-caption">caption</a></dt>
<dd></dd>
<dt><a href="#Property-captionID">captionID</a></dt>
<dd></dd>
<dt><a href="#Property-summary">summary</a></dt>
<dd></dd>
</dl>

<h3>Method Summary</h3>

<dl class="section-text">
<dt><a href="#Method-onCreate">onCreate</a></dt>
<dd>Script executed when the element is created in the Factory.</dd>
<dt><a href="#Method-onPageBreak">onPageBreak</a></dt>
<dd></dd>
<dt><a href="#Method-onPrepare">onPrepare</a></dt>
<dd>It is for a script startup phase. No data binding yet. The design of an element can be changed here.</dd>
<dt><a href="#Method-onRender">onRender</a></dt>
<dd>Script executed when the element is prepared for rendering in the Presentation engine.</dd>
</dl>

<h3>Slot Summary</h3>

<dl class="section-text">
<dt><a href="#Slot-columns">columns</a></dt>
<dd>Describes the columns that make up the grid.</dd>
<dt><a href="#Slot-rows">rows</a></dt>
<dd>Any number of row entries.</dd>
</dl>

<h3>Inherited Properties</h3>

<p class="section-text">
<a href="ReportItem.html#Property-ACLExpression">ACLExpression</a>, 
<a href="ReportItem.html#Property-allowExport">allowExport</a>, 
<a href="ReportItem.html#Property-bookmark">bookmark</a>, 
<a href="ReportItem.html#Property-bookmarkDisplayName">bookmarkDisplayName</a>, 
<a href="ReportItem.html#Property-boundDataColumns">boundDataColumns</a>, 
<a href="ReportItem.html#Property-cascadeACL">cascadeACL</a>, 
<a href="ReportElement.html#Property-comments">comments</a>, 
<a href="ReportItem.html#Property-cube">cube</a>, 
<a href="DesignElement.html#Property-customXml">customXml</a>, 
<a href="ReportItem.html#Property-dataBindingRef">dataBindingRef</a>, 
<a href="ReportItem.html#Property-dataSet">dataSet</a>, 
<a href="ReportElement.html#Property-displayName">displayName</a>, 
<a href="ReportElement.html#Property-displayNameID">displayNameID</a>, 
<a href="ReportElement.html#Property-eventHandlerClass">eventHandlerClass</a>, 
<a href="ReportElement.html#Property-extends">extends</a>, 
<a href="ReportItem.html#Property-height">height</a>, 
<a href="ReportItem.html#Property-multiViews">multiViews</a>, 
<a href="ReportElement.html#Property-name">name</a>, 
<a href="ReportElement.html#Property-newHandlerOnEachEvent">newHandlerOnEachEvent</a>, 
<a href="ReportItem.html#Property-paramBindings">paramBindings</a>, 
<a href="DesignElement.html#Property-propertyMasks">propertyMasks</a>, 
<a href="ReportItem.html#Property-pushDown">pushDown</a>, 
<a href="ReportItem.html#Property-refTemplateParameter">refTemplateParameter</a>, 
<a href="ReportItem.html#Property-style">style</a>, 
<a href="ReportItem.html#Property-toc">toc</a>, 
<a href="DesignElement.html#Property-userProperties">userProperties</a>, 
<a href="ReportElement.html#Property-viewAction">viewAction</a>, 
<a href="ReportItem.html#Property-visibility">visibility</a>, 
<a href="ReportItem.html#Property-width">width</a>, 
<a href="ReportItem.html#Property-x">x</a>, 
<a href="ReportItem.html#Property-y">y</a>, 
<a href="ReportItem.html#Property-zIndex">zIndex</a>
</p>
<h3>Style Properties</h3>

<p class="section-text">
<a href="Style.html#Property-backgroundAttachment">backgroundAttachment</a>, 
<a href="Style.html#Property-backgroundColor">backgroundColor</a>, 
<a href="Style.html#Property-backgroundImage">backgroundImage</a>, 
<a href="Style.html#Property-backgroundPositionX">backgroundPositionX</a>, 
<a href="Style.html#Property-backgroundPositionY">backgroundPositionY</a>, 
<a href="Style.html#Property-backgroundRepeat">backgroundRepeat</a>, 
<a href="Style.html#Property-backgroundSizeHeight">backgroundSizeHeight</a>, 
<a href="Style.html#Property-backgroundSizeWidth">backgroundSizeWidth</a>, 
<a href="Style.html#Property-bidiTextDirection">bidiTextDirection</a>, 
<a href="Style.html#Property-borderBottomColor">borderBottomColor</a>, 
<a href="Style.html#Property-borderBottomStyle">borderBottomStyle</a>, 
<a href="Style.html#Property-borderBottomWidth">borderBottomWidth</a>, 
<a href="Style.html#Property-borderLeftColor">borderLeftColor</a>, 
<a href="Style.html#Property-borderLeftStyle">borderLeftStyle</a>, 
<a href="Style.html#Property-borderLeftWidth">borderLeftWidth</a>, 
<a href="Style.html#Property-borderRightColor">borderRightColor</a>, 
<a href="Style.html#Property-borderRightStyle">borderRightStyle</a>, 
<a href="Style.html#Property-borderRightWidth">borderRightWidth</a>, 
<a href="Style.html#Property-borderTopColor">borderTopColor</a>, 
<a href="Style.html#Property-borderTopStyle">borderTopStyle</a>, 
<a href="Style.html#Property-borderTopWidth">borderTopWidth</a>, 
<a href="Style.html#Property-canShrink">canShrink</a>, 
<a href="Style.html#Property-color">color</a>, 
<a href="Style.html#Property-dateFormat">dateFormat</a>, 
<a href="Style.html#Property-dateTimeFormat">dateTimeFormat</a>, 
<a href="Style.html#Property-display">display</a>, 
<a href="Style.html#Property-fontFamily">fontFamily</a>, 
<a href="Style.html#Property-fontSize">fontSize</a>, 
<a href="Style.html#Property-fontStyle">fontStyle</a>, 
<a href="Style.html#Property-fontVariant">fontVariant</a>, 
<a href="Style.html#Property-fontWeight">fontWeight</a>, 
<a href="Style.html#Property-highlightRules">highlightRules</a>, 
<a href="Style.html#Property-letterSpacing">letterSpacing</a>, 
<a href="Style.html#Property-lineHeight">lineHeight</a>, 
<a href="Style.html#Property-mapRules">mapRules</a>, 
<a href="Style.html#Property-marginBottom">marginBottom</a>, 
<a href="Style.html#Property-marginLeft">marginLeft</a>, 
<a href="Style.html#Property-marginRight">marginRight</a>, 
<a href="Style.html#Property-marginTop">marginTop</a>, 
<a href="Style.html#Property-masterPage">masterPage</a>, 
<a href="Style.html#Property-numberAlign">numberAlign</a>, 
<a href="Style.html#Property-numberFormat">numberFormat</a>, 
<a href="Style.html#Property-orphans">orphans</a>, 
<a href="Style.html#Property-paddingBottom">paddingBottom</a>, 
<a href="Style.html#Property-paddingLeft">paddingLeft</a>, 
<a href="Style.html#Property-paddingRight">paddingRight</a>, 
<a href="Style.html#Property-paddingTop">paddingTop</a>, 
<a href="Style.html#Property-pageBreakAfter">pageBreakAfter</a>, 
<a href="Style.html#Property-pageBreakBefore">pageBreakBefore</a>, 
<a href="Style.html#Property-pageBreakInside">pageBreakInside</a>, 
<a href="Style.html#Property-showIfBlank">showIfBlank</a>, 
<a href="Style.html#Property-stringFormat">stringFormat</a>, 
<a href="Style.html#Property-textAlign">textAlign</a>, 
<a href="Style.html#Property-textIndent">textIndent</a>, 
<a href="Style.html#Property-textLineThrough">textLineThrough</a>, 
<a href="Style.html#Property-textOverline">textOverline</a>, 
<a href="Style.html#Property-textTransform">textTransform</a>, 
<a href="Style.html#Property-textUnderline">textUnderline</a>, 
<a href="Style.html#Property-timeFormat">timeFormat</a>, 
<a href="Style.html#Property-verticalAlign">verticalAlign</a>, 
<a href="Style.html#Property-whiteSpace">whiteSpace</a>, 
<a href="Style.html#Property-widows">widows</a>, 
<a href="Style.html#Property-wordSpacing">wordSpacing</a>
</p>
<h3>Description</h3>

<div class="section-text">
<p>A grid item contains a set of report items, and the items 
are arranged into a grid. Each cell in the grid can contain a single item. 
However, the user can easily add multiple items by placing a container into a 
cell, and placing other items into the container.</p>
<p>Grid layout is familiar to anyone who has used HTML 
tables, Word tables or Excel: data is divided into a series of rows and columns. 
Items can span both rows and columns. The grid layout is ideal for many simple 
reports and dashboards. Grids help align report items for a clean layout. The 
&quot;Grids&quot; section below explains how this feature works in BIRT.</p>
<p>The grid section is divided into rows and columns. Rows 
grow or shrink depending on content. Columns ensure that items line up 
vertically. Columns can also grow or shrink depending on their contents.</p>
<p>The following terminology applies to grids:</p>

<ul>
<li>Grid: a tabular layout with a fixed set of columns and variable number of rows. (Contrast this with a matrix that can have a variable set of columns.)</li>

<li>Column: a vertical slice though the grid. Columns help organize the layout, but do not represent a specific bit of data as they do in matrices.</li>

<li>Row: a horizontal slice through the grid.</li>

<li>Cell: a point at which a row and column intersect. A cell can span rows and columns.</li>

</ul>
<p>The grid layout is ideal for reports that will be 
exported to Excel or shown on the web.</p>
<p>The grid layout can be applied to a list to align column 
headings with detail rows. It can be applied to a dashboard to create a clean, 
organized layout. It can also be applied to the entire report to align data in a 
group of dashboards and lists.</p>

<h4>Benefits</h4>

<p>Grid layout is a well-understood, powerful way to 
simplify the layout of some or all of the report.</p>
<p>To understand why, simply consider a tool that provides only free-form layout. The simplest report layout is to 
place text onto lines, and fields into columns. A layout that supports just (x, 
y) positioning forces the user to manually align controls vertically and 
horizontally. Typical tools provide an align option to help with this ? the user 
can select a set of elements and cause them to be aligned with the same left or 
right side, or the same top or bottom position. However, manual alignment is not 
&quot;sticky.&quot; If the user decides to move the line or column position, he must 
manually move all the affected elements to the new location. The user must 
determine the affected controls manually.</p>
<p>Baseline alignment is very difficult with free-form 
layout. The developer must create the alignment manually though visual 
inspection and trial-and-error.</p>
<p>Another key limitation of free-form layout is the 
difficulty of aligning text along a baseline. Typical reporting elements are 
sized to a box that encloses the entire text, hence the baseline is somewhere in 
the middle of the element. The actual position depends on the specific font, 
font size, and the output device. Therefore, baseline alignment is virtually 
impossible using free-form layout. The best the developer can do is to eyeball 
the alignment to get close to the desired result.</p>
<p>Grid layout avoids the problems of free-form layout:</p>

<ul>
<li>Automates the task of aligning report elements onto lines.</li>

<li>Automates the task of aligning elements vertically into columns.</li>

</ul>
<p>Grids also make it very easy for the developer to create 
a simple report by dragging elements into the report design. The grid ensures 
that report items are aligned, and automatically sizes the columns to fit the 
contents.</p>


<h4>Visual Appearance</h4>

<p>The developer can set a number of properties for the grid 
as a whole.</p>

<ul>
<li>Style. The style defines the font to use within grid cells, the border style for the grid, fill color, and so on.</li>

<li>Fixed or variable size. A grid will normally adjust based on the available space on the page. When viewed on the web, the grid columns will expand to make use of the full width of the browser window in the expected way.</li>

<li>Row alignment: how to align items within a row. Options are top, middle, bottom or baseline (described below).</li>

</ul></div>
<h1>Property Detail</h1>

<h2><a name="Property-caption">caption Property</a></h2>

<p class="section-text"></p>
<h3>Details</h3>

<table class="detail-table">
<tr><td>Type:</td>
<td><a href="../types.html#string">string</a></td></tr>
<tr><td>Since:</td>
<td>2.3</td></tr>
<tr><td>Required:</td>
<td>No</td></tr>
<tr><td>Display Name:</td>
<td>Caption</td></tr>
<tr><td>JavaScript Type:</td>
<td></td></tr>
<tr><td>Default Value:</td>
<td>None</td></tr>
<tr><td>Inherited:</td>
<td>Yes</td></tr>
<tr><td>Runtime Settable:</td>
<td>No</td></tr>
<tr><td>Property Sheet Visibility:</td>
<td>Visible</td></tr>
<tr><td>Property Sheet Group:</td>
<td>Top</td></tr>
</table>


<hr>
<h2><a name="Property-captionID">captionID Property</a></h2>

<p class="section-text"></p>
<h3>Details</h3>

<table class="detail-table">
<tr><td>Type:</td>
<td><a href="../types.html#resourceKey">resourceKey</a></td></tr>
<tr><td>Since:</td>
<td>2.3</td></tr>
<tr><td>Required:</td>
<td>No</td></tr>
<tr><td>Display Name:</td>
<td>Caption key</td></tr>
<tr><td>JavaScript Type:</td>
<td></td></tr>
<tr><td>Default Value:</td>
<td>None</td></tr>
<tr><td>Inherited:</td>
<td>Yes</td></tr>
<tr><td>Runtime Settable:</td>
<td>Yes</td></tr>
<tr><td>Property Sheet Visibility:</td>
<td>Visible</td></tr>
<tr><td>Property Sheet Group:</td>
<td>Top</td></tr>
</table>


<hr>
<h2><a name="Property-summary">summary Property</a></h2>

<p class="section-text"></p>
<h3>Details</h3>

<table class="detail-table">
<tr><td>Type:</td>
<td><a href="../types.html#string">string</a></td></tr>
<tr><td>Since:</td>
<td>2.3</td></tr>
<tr><td>Required:</td>
<td>No</td></tr>
<tr><td>Display Name:</td>
<td>Summary</td></tr>
<tr><td>JavaScript Type:</td>
<td></td></tr>
<tr><td>Default Value:</td>
<td>None</td></tr>
<tr><td>Inherited:</td>
<td>Yes</td></tr>
<tr><td>Runtime Settable:</td>
<td>No</td></tr>
<tr><td>Property Sheet Visibility:</td>
<td>Visible</td></tr>
<tr><td>Property Sheet Group:</td>
<td>Top</td></tr>
</table>

<h1>Method Detail</h1>

<h2><a name="Method-onCreate">onCreate Method</a></h2>

<p class="section-text">Script executed when the element is created in the Factory.</p>
<h3>Synopsis
</h3>

<p class="section-text"><code>None&nbsp;obj.onCreate(&nbsp;)</code></p>
<h3>Details
</h3>

<table class="detail-table">
<tr><td>Since:</td>
<td>1.0</td></tr>
<tr><td>Context:</td>
<td>factory</td></tr>
<tr><td>Arguments:</td>
<td>None</td></tr>
<tr><td>Return Type:</td>
<td>None</td></tr>
</table>

<h3>Description</h3>

<div class="section-text">
<p>Executed when the element is created in the Factory. Called after the item is created, but before 
the item is saved to the report document file. See the scripting spec for additional information 
about this script. Applications should perform visual customization in the on-render script instead.</p></div>

<hr>
<h2><a name="Method-onPageBreak">onPageBreak Method</a></h2>

<p class="section-text"></p>
<h3>Synopsis
</h3>

<p class="section-text"><code>None&nbsp;obj.onPageBreak(&nbsp;)</code></p>
<h3>Details
</h3>

<table class="detail-table">
<tr><td>Since:</td>
<td>2.1</td></tr>
<tr><td>Context:</td>
<td>presentation</td></tr>
<tr><td>Arguments:</td>
<td>None</td></tr>
<tr><td>Return Type:</td>
<td>None</td></tr>
</table>


<hr>
<h2><a name="Method-onPrepare">onPrepare Method</a></h2>

<p class="section-text">It is for a script startup phase. No data binding yet. The design of an element can be changed here.</p>
<h3>Synopsis
</h3>

<p class="section-text"><code>None&nbsp;obj.onPrepare(&nbsp;)</code></p>
<h3>Details
</h3>

<table class="detail-table">
<tr><td>Since:</td>
<td>2.0</td></tr>
<tr><td>Context:</td>
<td>startup</td></tr>
<tr><td>Arguments:</td>
<td>None</td></tr>
<tr><td>Return Type:</td>
<td>None</td></tr>
</table>

<h3>Description</h3>

<div class="section-text">
<p>It is for a script startup phase. No data binding yet. The design of an element can be changed here.</p></div>

<hr>
<h2><a name="Method-onRender">onRender Method</a></h2>

<p class="section-text">Script executed when the element is prepared for rendering in the Presentation engine.</p>
<h3>Synopsis
</h3>

<p class="section-text"><code>None&nbsp;obj.onRender(&nbsp;)</code></p>
<h3>Details
</h3>

<table class="detail-table">
<tr><td>Since:</td>
<td>1.0</td></tr>
<tr><td>Context:</td>
<td>presentation</td></tr>
<tr><td>Arguments:</td>
<td>None</td></tr>
<tr><td>Return Type:</td>
<td>None</td></tr>
</table>

<h3>Description</h3>

<div class="section-text">
<p>Executed when the element is prepared for rendering in the Presentation engine. Changes made to the 
element are written to the target output format, but not saved to the report document file. This is the
preferred place for visual customizations.</p></div>
<h1>Slot Detail</h1>

<h2><a name="Slot-columns">columns Slot</a></h2>

<p class="section-text">Describes the columns that make up the grid.</p>
<h3>Details</h3>

<table class="detail-table">
<tr><td>Display Name:</td>
<td>Columns</td></tr>
<tr><td>Since:</td>
<td>1.0</td></tr>
<tr><td>XML Element:</td>
<td>None. (The contents appear directly within the container element.)</td></tr>
<tr><td>Contents:</td>
<td>List of <a href="Column.html">Column</a></td></tr>
<tr><td>Default Style:</td>
<td>None</td></tr>
</table>

<h3>Description</h3>

<div class="section-text">
<p><p>This property describes the columns within the table. 
This property is optional. If omitted, BIRT infers the columns from the table 
structure itself, and BIRT will size the columns based on their contents. If 
provided, then the table must contain no more than the number of columns 
described. Use this property when you want to control the size, color, border, 
or other properties of each column.</p></p></div>
<h3>See Also</h3>

<div class="section-text">
<p>The Column Definition structure in the <i>ROM List &amp; 
Table Specification</i>.</p></div>

<hr>
<h2><a name="Slot-rows">rows Slot</a></h2>

<p class="section-text">Any number of row entries.</p>
<h3>Details</h3>

<table class="detail-table">
<tr><td>Display Name:</td>
<td>Rows</td></tr>
<tr><td>Since:</td>
<td>1.0</td></tr>
<tr><td>XML Element:</td>
<td>None. (The contents appear directly within the container element.)</td></tr>
<tr><td>Contents:</td>
<td>List of <a href="Row.html">Row</a></td></tr>
<tr><td>Default Style:</td>
<td>None</td></tr>
</table>

<h3>Description</h3>

<div class="section-text">
<p><p>Contains a list of the rows that make up the grid. Grids 
are defined in &quot;row-major&quot; format: as a list of rows that contain cells.</p>
<p></p></p></div>
</body>
</html>
